/*
 * Copyright (C) 2010-2011 Comcast Cable.  All Rights Reserved.
 */
package com.hercules.android.receiver.util.evaluators;

import com.hercules.android.receiver.AndroidReceiver;

/**
 * <p>
 * This interface represents an expression evaluator that defines the only method for evaluating an expression with
 * specific format.
 * </p>
 *
 * <p>
 * <strong>Thread Safety: </strong> Implementations of this interface are not required to be thread safe.
 * </p>
 *
 * @author saarixx, sparemax
 * @version 1.0
 */
public interface ExpressionEvaluator {
    /**
     * <p>
     * Evaluates the given expression.
     * </p>
     *
     * @param sourceId
     *            the ID of the source XRE object.
     * @param receiver
     *            the Android receiver.
     * @param expression
     *            the expression to be evaluated.
     *
     * @return the evaluation result.
     *
     * @throws IllegalArgumentException
     *             if expression is <code>null</code>/empty, sourceId is not positive or receiver is <code>null</code>.
     * @throws InvalidExpressionException
     *             if the given expression has invalid format.
     * @throws InvalidAndroidReceiverStateException
     *             if the provided receiver or some XRE object was not properly initialized.
     * @throws InvalidPathException
     *             if some XRE object path specified in the expression is invalid.
     */
    public double evaluateExpression(String expression, int sourceId, AndroidReceiver receiver)
        throws InvalidExpressionException, InvalidAndroidReceiverStateException, InvalidPathException;
}
